home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / fish / 676-700 / 696 / tinyclock / tinyclock.doc < prev    next >
Text File  |  1995-03-18  |  8KB  |  221 lines
  1. short: a cute little analog clock (2.x only)
  2.  
  3. TinyClock v1.04
  4. ---------------
  5. Copyright (C) Martin W. Scott, 1992.
  6. NB: TinyClock only works with AmigaDos 2.0 or higher (sorry).
  7. [Released in June '92.]
  8.  
  9. TinyClock is CARDWARE, ie. if you like and use it, send me a postcard
  10. from your area -- it's not too much to ask, is it?  My address is at the
  11. end of this document.
  12.  
  13. History
  14. -------
  15.  v1.04    - alarm window now has 'Time now' gadget to fill in current time.
  16.  
  17.     - increased audio priority of beep, so sound gets through when it
  18.       needs to (unless programs ask for the audio.device with a higher
  19.       priority than they ought too...).
  20.  
  21.  v1.03    - now has alarm facility.
  22.  
  23.     - fixed small bugette whereby minute hand was not pointing to
  24.       the exactly ideal place -- now you can read-off the minutes
  25.       fairly accurately with a small window.
  26.  
  27.  v1.02    - now optionally pops its window to front when obscured; thus,
  28.       v1.01 and below .config files will not be loaded -- sorry...
  29.  
  30.  v1.01    - now sets its priority to 10, to update on time regardless
  31.       of heavy CPU load.
  32.  
  33.     - improved beep sound (doesn't 'grate' so much now).
  34.  
  35.  v1.0   - initial release.
  36.  
  37. Overview
  38. --------
  39. There are far too many clock programs for the Amiga -- it seems that
  40. no-one likes what's on offer and so writes their own, and places it in
  41. the Public Domain. And good, too: we have a LOT of choice.
  42.  
  43. But what about analog clocks? Well, there's Commodore's clock, but that
  44. uses over 40K memory and too much of the processor. Then there's
  45. WizardClock, but again that is big, and not resizeable (though it is
  46. neat, and has lots of nice extras). And lastly (as far as I know) there's
  47. FAClock, but the less said about that the better...
  48.  
  49. But, like so many before me, the clock I wanted wasn't there. One that
  50. came close was a small analog clock by Matt Dillon. It was rather too
  51. limited though. However, using that source as a starting point, I
  52. produced TinyClock. Much has been added, for both aesthetics and
  53. functionality. Here's a rundown of TinyClock's features:
  54.  
  55.     -    Resizeable analog display;
  56.  
  57.     -    Optionally pops its window to front when obscured;
  58.  
  59.     -    Colors used in clock rendering can be changed as desired;
  60.  
  61.     -    Can save position etc. for subsequent runs;
  62.  
  63.     -    Optionally chirps every quarter-hour, and twice on the hour;
  64.  
  65.     -    Has an alarm facility;
  66.  
  67.     -    Whole window is a 'drag bar', except right-hand and bottom
  68.     edges, which act as a 'sizing gadget';
  69.  
  70.     -    Displays day and date in MenuBar when window is active;
  71.  
  72.     -    WB 2.0 'icon look', with menus that use screen's font;
  73.  
  74.     -    Small binary (about 7K), uses only 14K memory running;
  75.  
  76.     -    Uses tiny amount of processor (only redraws when necessary).
  77.  
  78. My aim is to make TinyClock the clock you want, as ubiquitous as xclock
  79. on Sun Workstations.
  80.  
  81. Usage Notes
  82. -----------
  83. To start, double click on the TinyClock icon. The first time you run,
  84. the clock will use default sizes and colors - configure it the way you
  85. want, and select 'Save prefs' from the TinyClock menu. TinyClock will
  86. then always use these settings. (The preferences are saved to a file
  87. called 'S:TinyClock.config'.)
  88.  
  89. I find the best position to be the top right-hand corner of the screen.
  90.  
  91. You may of course start TinyClock from the CLI, but it does not
  92. self-detatch, and would have to be 'run' if you wanted to continue using
  93. the CLI.
  94.  
  95. Best way to start it, though, is to shove it in your WBStartup drawer;
  96. if you do, set the DONOTWAIT tooltype for Workbench.
  97.  
  98. To keep binary size down, TinyClock takes no command-line options or
  99. tooltypes - it uses a config-file instead, as mentioned above. A stack
  100. of 2500 bytes seems sufficient for TinyClock (I've had no problems).
  101.  
  102. Strange behaviour
  103. -----------------
  104. Since TinyClock updates once every four seconds, it will take (at most)
  105. that long for its window to come to the front if obscured, and for the
  106. display to reflect a new system time. However, the display will update
  107. on the minute, not a few seconds either side.
  108.  
  109. The imagery used to draw the clock (hands, pips) is NOT width-scaled
  110. (unlike the Commodore clock). TinyClock is intended to be just that, and
  111. looks pretty ugly if made large. But then, who wants a clock taking up
  112. half the screen?
  113.  
  114. No other unexpected behaviour is known.
  115.  
  116. The Menus
  117. ---------
  118. Self-explanatory, I hope. Here's a quick rundown though...
  119.  
  120. TinyClock menu (all items have shortcuts as indicated):
  121.  
  122.  To Front     F  Sends clock window to front (there are no depth gadgets)
  123.  To Back      B  Sends clock window to back
  124.  Auto Front   A  Bring window to front when it's obscured by others
  125.  Chirp          C  If checked, will beep on quarter-hour (& twice on the hour)
  126.  Reset prefs  R  Reloads previously saved configuration
  127.  Save prefs   S  Save current position/size/colors to configuration file
  128.  About...     ?  Displays a small message from your sponsor
  129.  Quit          Q  You don't want to do that...
  130.  
  131. Colors menu:     (0-3 denote system colors)
  132.  
  133.  Background     The color of the clock window
  134.  Hour hand     The color of the hour hand
  135.  Minute hand     The color of the minute hand
  136.  Pips         The color of the pips (hour marks)
  137.  
  138. If using Workbench default (2.0) colors,
  139.     0 is lightish-grey,
  140.     1 is black,
  141.     2 is white,
  142.     3 is mid-blue.
  143.  
  144. Of course, some combinations look better than others, and some are
  145. downright useless (like black hands on a black background...).
  146.  
  147. Alarm menu:
  148.  
  149.  Set...        Pops up a requester letting you set alarm time
  150.  Alarm On
  151.  Alarm Off    Have a wild guess...
  152.  
  153. Usage of alarm requester should be fairly obvious. It uses a 24-hour
  154. clock, with hour 00 meaning midnight. The alarm time is stored in the
  155. .config file. Once you've modified the alarm time, click 'OK' to accept.
  156. Clicking 'Cancel' means that you're (session) preferences go unchanged.
  157. Clicking 'Time now' fills in the current time, in case the time you want
  158. to set is close to this.
  159.  
  160. Once you've set your alarm time, you should select the 'Alarm On' menu
  161. item if it's not already checked, to enable alarm signals. If you want
  162. to use the same alarm time regularly, you may 'Save Prefs'.
  163.  
  164. One other thing: while you are setting the alarm time, the clock window
  165. won't update. This shouldn't be a major hassle.
  166.  
  167. That's the menus. As mentioned in the 'features' list, almost the whole
  168. window is a 'drag bar' (this is like some programs' iconified states).
  169. The picture below shows what parts of the window do what:
  170.  
  171.     +-------------------------+-+
  172.     |              | |
  173.     |              | |
  174.     |    Click here to      | <----    Click in this region
  175.     |              | |
  176.     |      position      | |          to resize window
  177.     |              | |
  178.     |       window      | |
  179.     |              | |
  180.     |              | |
  181.     +-------------------------+ |
  182.     +---------------------------+
  183.  
  184. Author and Credits
  185. ------------------
  186. Original clock code was (C) Matt Dillon (although it's now unrecognisable).
  187. TinyClock is written in C and compiled with SAS (Lattice) C v5.10a.
  188. Thanks to Mike Meyer et al. for Mg3 (the best pd text editor) and Steve
  189. Koren for SKsh. Pierre Ardichvile suggested the pop-to-front option.
  190. GadToolsBox v1.3 generated the alarm window and gadgets - thanks to Jaba
  191. Development for a great program.
  192.  
  193. I am always happy to receive bug-reports, comments or suggestions for
  194. enhancement of programs I write. I can be contacted by postal mail at:
  195.  
  196.     Martin W. Scott,
  197.     23 Drum Brae North,
  198.     Edinburgh,
  199.     EH4 8AT
  200.     United Kingdom.
  201.  
  202. Send your postcards to that address too...
  203. You may also contact me by email: mws@castle.ed.ac.uk
  204.  
  205. TinyClock is freely redistributable, as long as this documentation
  206. (unaltered) accompanies it. It may not be sold for profit or included in
  207. any commercial product (and that includes magazines) without permission.
  208. Remember, TinyClock is CARDWARE (see head of document). I'm rather hacked
  209. off about the lack of feedback for programs I write; no postcards => no
  210. updates or future programs.
  211.  
  212. Contributions are not obligatory, but are always welcome (I'm yet
  213. another poor student).
  214.  
  215. Oh, and I'm happy to do foreign language versions if you want to give me
  216. translations of *every* menu in the program.
  217.  
  218. Enjoy!
  219.  
  220.  Martin.
  221.